.TH findblk 1
'''
.SH NAME
\fBfindblk\fR \- locate block device and symlink named partitions
'''
.SH SYNOPSIS
\fBfindblk\fR \fIwwid:eui.0123456789ABCD\fI \fI1\fB:\fIboot\fR \fI2\fB:\fIroot\fR ...
.P
Find block device described by \fIwwid:eui.0123456789ABCD\fR, symlink its 1st
partition to \fB/dev/mapper/\fIboot\fR and 2nd partition to \fB/dev/mapper/\fIroot\fR.
'''
.SH DESCRIPTION
\fBfindblk\fR is meant to be run from initrd to locate system partitions.
.P
By the time the kernel starts running initrd code, the device containing
the real root partition may be ready yet. Furthermore, it may not be clear
what's the name of the device node for the partition, because or unreliable
initialization order, so a simple mount would not work:
.P
.nf
    mount /dev/\fIsda2\fR /newroot          # or is it sdb2?
    mount /dev/\fIsda1\fR /newroot/boot
.fi
.P
This tool waits for block devices to appear, and attempt to identify
particular devices using hardware serials or partition table IDs,
effectively assigning persistent names than can be passed to mount:
.P
.nf
    findblk \fIwwid:....\fR 1:boot 2:root         # this time it's is sda
    kmount /dev/mapper/root /newroot        # root is a symlink to ../sda2
    kmount /dev/mapper/boot /newroot/boot   # boot is a symlink to ../sda1
.fi
.P
By the time kmount gets to run, the device is ready, and the name that
gets passed does not depend on kernel initialization order.
.P
This trick is not limited to kmount. The mapper symlinks can be used to
run fsck, disk encryption tooling and pretty much anything else that needs
a block device name.
'''
.SH OPTIONS
Several properties can be used to identify a particular device:
.IP "\fBname:\fIsda\fR" 4
Raw kernel device node name; \fBfindblk\fR will wait for it to appear.
.IP "\fBmbr:\fI00112233\fR" 4
MBR disk identifier. Can be set with \fBfdisk\fR or other similar tools.
If specified, \fBfindblk\fR will attempt to read the device.
.IP "\fBgpt:\fI0011-2233-...\fR" 4
GPT disk UUID. Similar to MBR disk ID, for GPT-partitioned drives.
.IP "\fBwwid:\fI001122334455...\fR" 4
SCSI disk WWID, hardware identifier.
Matches /sys/block/\fIsda\fR/wwid or /sys/block/\fIsda\fR/device/wwid.
SATA and NVME typically provide it.
.IP "\fBcid:\fI001122..\fR" 4
SD/MMC card ID, hardware identifier.
Matches /sys/block/\fImmcblk0\fR/device/cid.
Typically only available if the card shows up as \fImmcblkN\fR in Linux;
not available via USB SD readers.
.IP "\fBserial:\fI...\fR" 4
Generic serial entry. May be available for some USB devices.
Matches /sys/block/\fIsda\fR/device/serial.
.P
Using \fBmbr\fR and \fBgpt\fR identifier forces \fBfindblk\fR to read a small
amount of data from all block devices available in the system until it finds
the one that matches. On the flip side, both are easily editable and work the
same way with pretty much any variety of block devices, whereas hardware IDs
tend to be bus-specific.
'''
.SH NOTES
In case device initialization relies on modaliases and dynamically loaded
kernel modules, this tool must be run alongside some udev agent handling
modalias requests. #TODO
.P
The time this tool spends waiting for devices is limited to 5s.
If the time runs out and the requested device has not been found, findblk
exists with error, likely prompting a reboot.
.P
Both /dev and /sys must be mounted prior to running \fBfindblk\fR.
'''
.SH CAVEATS
This tool is meant for the cases when a single device (possibly containing
multiple partitions) needs to be located. It can be used to locate multiple
devices, just run several times with approriate device IDs. It would work,
but it may be suboptimal, since every invocation will go through all devices
available in the system.
'''
.SH SEE ALSO
\fBblkpass\fR(8).
